Inside Macintosh: QuickTime Components /: Chapter 11 - Clock Components

Summary of Clock Components

C Summary

Constants

/* type value */
#define clockComponentType    'clok'      /* clock component */
/* subtype values */
#define systemTickClock       'tick'      /* system tick clock */
#define systemMicrosecondClock 'micr'     /* system microsecond clock */
#define systemSecondClock      'seco'     /* system second clock */
#define systemMillisecondClock 'mill'     /* system millisecond clock */
/* constants for manipulating clock component capability flags */
enum{
   kClockRateIsLinear = 1,          /* clock keeps constant rate */
   kClockImplementsCallBacks = 2    /* clock supports callback events */
};
#define ClockGetTime GetClockTime
/* constants to refer to request codes for supported functions */
enum {
   kClockGetTimeSelect           = 0x1,   /* ClockGetTime */
   kClockNewCallBackSelect       = 0x2,   /* ClockNewCallBack */
   kClockDisposeCallBackSelect   = 0x3,   /* ClockDisposeCallBack */
   kClockCallMeWhenSelect        = 0x4,   /* ClockCallMeWhen */
   kClockCancelCallBackSelect    = 0x5,   /* ClockCancelCallBack */
   kClockRateChangedSelect       = 0x6,   /* ClockRateChanged */
   kClockTimeChangedSelect       = 0x7,   /* ClockTimeChanged */
   kClockSetTimeBaseSelect       = 0x8,   /* ClockSetTimeBase */
   kClockStartStopChangedSelect  = 0x9,   /* ClockStartStopChanged */
   kClockGetRateSelect           = 0xA    /* ClockGetRate */
};
enum {
   qtcbNeedsRateChanges       = 1,/* wants to know about rate changes */
   qtcbNeedsTimeChanges       = 2,/* wants to know about time changes */
   qtcbNeedsStartStopChanges  = 4 /* wants to know when time base start 
                                    or stop has changed */
};
/* values for callBackType parameter of ClockNewCallBack function that
   indicate when a callback event is to be invoked */

enum
   {
   callBackAtTime          = 1,     /* at specific time */
   callBackAtRate          = 2,     /* when the rate for the time base
                                       reaches a specific value */
   callBackAtTimeJump      = 3,     /* when a program changes the time value
                                       for a time base */
   };
typedef unsigned short QTCallBackType;
/* callback equates--values for the parameter param1 of the
   ClockCallMeWhen function that indicate when the callback function should
   be called */

enum
   {
   triggerTimeFwd       = 0x0001,/* when current time exceeds trigger time
                                    going forward */
   triggerTimeBwd       = 0x0002,/* when current time exceeds trigger time
                                    going backward */
   triggerTimeEither    = 0x0003,/* when curTime exceeds triggerTime going 
                                    either direction */
   triggerRateLT        = 0x0004,/* when rate changes to less than trigger
                                    value */
   triggerRateGT        = 0x0008,/* when rate changes to greater than trigger
                                    value */
   triggerRateEqual     = 0x0010,/* when rate changes to equal trigger 
                                    value */
   triggerRateLTE       = triggerRateLT | triggerRateEqual,
                                 /* when rate changes to a value less than
                                    or equal to param2 rate */
   triggerRateGTE       = triggerRateGT | triggerRateEqual,
                                 /* when rate changes to value greater than
                                    or equal to param2 rate */
   triggerRateNotEqual  = triggerRateGT | triggerRateEqual | triggerRateLT,
                                 /* when rate changes to value not equal to
                                    param2 rate */
   triggerRateChange    = 0,     /* whenever rate changes */
   };
typedef unsigned short QTCallBackFlags;

Data Type

struct QTCallBackHeader {
      long     callBackFlags;    /* flags used by clock component to
                                    communicate scheduling data about
                                    callback to Movie Toolbox */
      long     reserved1;        /* reserved for use by Apple */
      char     qtPrivate[40];    /* reserved for use by Apple */
};

Clock Component Functions

Getting the Current Time

pascal ComponentResult ClockGetTime
(ComponentInstance aClock, TimeRecord *out);

Using the Callback Functions

pascal QTCallBack ClockNewCallBack
(ComponentInstance aClock, TimeBase tb,
short callBackType);
pascal ComponentResult ClockCallMeWhen
(ComponentInstance aClock, QTCallBack cb,
long param1, long param2, long param3);
pascal ComponentResult ClockCancelCallBack
(ComponentInstance aClock, QTCallBack cb);
pascal ComponentResult ClockDisposeCallBack
(ComponentInstance aClock, QTCallBack cb);

Managing the Time

pascal ComponentResult ClockTimeChanged
(ComponentInstance aClock, QTCallBack cb);
pascal ComponentResult ClockRateChanged
(ComponentInstance aClock, QTCallBack cb);
pascal ComponentResult ClockStartStopChanged 
(ComponentInstance aClock, QTCallBack cb, Boolean startChanged, Boolean stopChanged);
pascal ComponentResult ClockSetTimeBase
(ComponentInstance clock, TimeBase tb);

Movie Toolbox Clock Support Functions

pascal OSErr AddCallBackToTimeBase
(QTCallBack cb);
pascal void ExecuteCallBack
(QTCallBack cb);
pascal OSErr RemoveCallBackFromTimeBase
(QTCallBack cb);
pascal QTCallBack GetFirstCallBack
(TimeBase tb);
pascal QTCallBack GetNextCallBack
(QTCallBack cb);

Pascal Summary

Constants

CONST    
   {type value}
   clockComponentType            = 'clok';   {clock component}
   
   {subtype values}
   systemTickClock               = 'tick';   {system tick clock}
   systemMicrosecondClock        = 'micr';   {system microsecond clock}
   systemSecondClock             = 'seco';   {system second clock}
   systemMillisecondClock        = 'mill';   {system microsecond clock}

   {constants for manipulating clock component capability flags}
   kClockRateIsLinear            = 1;        {linear clock rate}
   kClockImplementsCallBacks     = 2;        {clock to implement callback }
                                             { routines}
   {constants to refer to request codes for supported routines}
   kClockGetClockTimeSelect      = $1;    {ClockGetTime}
   kClockNewCallBackSelect       = $2;    {ClockNewCallBack}
   kClockDisposeCallBackSelect   = $3;    {ClockDisposeCallBack}
   kClockCallMeWhenSelect        = $4;    {ClockCallMeWhen}
   kClockCancelCallBackSelect    = $5;    {ClockCancelCallBack}
   kClockRateChangedSelect       = $6;    {ClockRateChanged}
   kClockTimeChangedSelect       = $7;    {ClockTimeChanged}
   kClockSetTimeBaseSelect       = $8;    {ClockSetTimeBase}
   kClockStartStopChangedSelect  = $9;    {ClockStartStopChanged}
   kClockGetRateSelect           = $A;    {ClockGetRate}
   qtcbNeedsRateChanges       = 1;  {wants to know about rate changes}
   qtcbNeedsTimeChanges       = 2;  {wants to know about time changes}
   qtcbNeedsStartStopChanges  = 4;  {wants to know when time base start }
                                    { or stop has changed}
{values for callBackType parameter of ClockNewCallBack function that }
{ indicate when a callback event is to be invoked}
   callBackAtTime          = 1;     {at specific time}
   callBackAtRate          = 2;     {when the rate for the time base }
                                    { reaches a specific value}
   callBackAtTimeJump      = 3;     {when a program changes the time value }
                                    { for a time base}
{values for the parameter param1 of ClockCallMeWhen function that indicate }
{ when callback function should be called}
triggerTimeFwd       = $0001; {when current time exceeds trigger time going }
                              { forward}
triggerTimeBwd       = $0002; {when current time exceeds trigger time going }
                              { backward}
triggerTimeEither    = $0003; {when current time exceeds trigger time going }
                              { either direction}
triggerRateLT        = $0004; {when rate changes to less than trigger value}
triggerRateGT        = $0008; {when rate changes to greater than trigger }
                              { value}
triggerRateEqual     = $0010; {when rate changes to equal trigger value}
triggerRateLTE       = $0014; {when rate changes to less than or equal }
                              { trigger value}
triggerRateGTE       = $0018; {when rate changes to greater than or equal }
                              { to trigger value}
triggerRateNotEqual  = $001C; {when rate is not equal to trigger value}
triggerRateChange    = 0;     {whenever rate changes}

Data Type

TYPE  
   QTCallBack                    = ^CallBackRecord;
   QTCallBackHeader = 
      RECORD
         callBackFlags:    LongInt;    {component flags about callback }
                                       { events}
         reserved1:        LongInt;    {reserved}
         qtPrivate:        ARRAY[0..39] OF Byte;
                                       {reserved}
      END;
   QTCallBackFlags   = Byte;
   QTCallBackType    = Byte;
   QTCallBackProc    = ProcPtr;

Clock Component Routines

Getting the Current Time

FUNCTION ClockGetTime (aClock: ComponentInstance; 
VAR out: TimeRecord): ComponentResult;

Using the Callback Functions

FUNCTION ClockNewCallBack (aClock: ComponentInstance; tb: TimeBase; 
callBackType: Integer): QTCallBack;
FUNCTION ClockCallMeWhen (aClock: ComponentInstance; cb: QTCallBack; 
param1: LongInt; param2: LongInt; 
param3: LongInt): ComponentResult;
FUNCTION ClockCancelCallBack
(aClock: ComponentInstance; 
cb: QTCallBack): ComponentResult;
FUNCTION ClockDisposeCallBack
(aClock: ComponentInstance; 
cb: QTCallBack): ComponentResult;

Managing the Time

FUNCTION ClockTimeChanged (aClock: ComponentInstance; 
cb: QTCallBack): ComponentResult;
FUNCTION ClockRateChanged (aClock: ComponentInstance; 
cb: QTCallBack): ComponentResult;
FUNCTION ClockStartStopChanged
(clock: ComponentInstance; cb: QTCallBack; startChanged: Boolean; stopChanged: Boolean): ComponentResult;
FUNCTION ClockSetTimeBase (aClock: ComponentInstance; 
tb: TimeBase): ComponentResult;

Movie Toolbox Clock Support Routines

FUNCTION AddCallBackToTimeBase
(cb: QTCallBack): OSErr;
PROCEDURE ExecuteCallBack (cb: QTCallBack);
FUNCTION RemoveCallBackFromTimeBase 
(cb: QTCallBack): OSErr;
FUNCTION GetFirstCallBack (tb: TimeBase): QTCallBack;
FUNCTION GetNextCallBack 	(cb: QTCallBack): QTCallBack;